JBoss.orgCommunity Documentation

Chapter 6. Client JAIN SLEE Applications

6.1. XDM Client JAIN SLEE Enabler
6.2. The Mobicents SIP Event Publication Client Enabler
6.2.1. Integrating the Mobicents SIP Event Publication Client Enabler
6.2.2. Using the Mobicents SIP Event Publication Client Enabler
6.3. The Mobicents SIP Event Subscription Client Enabler
6.3.1. Integrating the Mobicents SIP Event Subscription Client Enabler
6.3.2. Using the Mobicents SIP Event Subscription Client Enabler
6.4. The Mobicents Presence Client Enabler
6.4.1. Integrating the Mobicents Presence Client Enabler
6.4.2. Using the Mobicents Presence Client Enabler
6.5. Client Application Examples

The Mobicents SIP Presence Service is built on top of Mobicents JAIN SLEE, which means JAIN SLEE applications can be deployed and run in same JVM as the servers. Better yet, there are XDM and SIP Presence client enablers which can be integrated in such JAIN SLEE applications, allowing an easy interaction with the platform servers.

The Mobicents SIP Presence exposes a JAIN SLEE enabler for applications which want to interact as clients of the XDM Server. The enabler is an extension of the XDM Client Enabler which exists in Mobicents JAIN SLEE, the only difference is that upon requests targeting the local and integrated XDM Server, the enabler does not uses XCAP or SIP network protocols, thus providing better performance and less overhead to network communications.

Please refer to the bundled JAIN SLEE documentation for complete details about how to integrate the enabler, the only difference to note in this document, is the configuration of the client JAIN SLEE application SBB's XML Descriptor. The extended XDM Client Enabler SBB has the following ID:



    <sbb-name>InternalXDMClientControlSbb</sbb-name>
    <sbb-vendor>org.mobicents</sbb-vendor>
    <sbb-version>1.0</sbb-version>      
        
        

In concrete this means that when integrating the enabler, the Parent's (the client application) Sbb XML Descriptor will refer the ID above instead of:



    <sbb-name>XDMClientChildSbb</sbb-name>
    <sbb-vendor>org.mobicents</sbb-vendor>
    <sbb-version>1.0</sbb-version>      
        
        

The Mobicents SIP Event Publication exposes a JAIN SLEE enabler for applications which want to interact as clients of a SIP Event Publication Server. The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.

The Enabler consists in an SBB which can be used in child relations, with a simple synchronous interface.

This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.

In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.

In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.

The Mobicents SIP Event Publication Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sipevent.server.publication.PublicationClientControlSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sipevent.server.publication.PublicationClientControl interfaces, the latter declares the methods which can be used to interact with the PS and/or RLS:



package org.mobicents.slee.sipevent.server.publication;
public interface PublicationClientControl {
    public Result newPublication(String entity, String eventPackage,
            String document, String contentType, String contentSubType,
            int expires);
    public Result refreshPublication(String entity, String eventPackage,
            String eTag, int expires);
    public Result modifyPublication(String entity, String eventPackage,
            String eTag, String document, String contentType,
            String contentSubType, int expires);
    public int removePublication(String entity, String eventPackage, String eTag);
}
        
        

The Mobicents SIP Event Publication exposes a JAIN SLEE enabler for applications which want to interact as clients of a SIP Event Subscription Server, such as a PS or RLS. The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.

The Enabler consists in an SBB which can be used in child relations, with a simple asynchronous interface.

This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.

In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.

The Mobicents SIP Event Subscription Client Enabler Sbb provides asynchronous callbacks to the Parent's Sbb, and that can only be achieved if the Parent's SbbLocalObject extends a specific Java interface, deployed also by the Enabler, and provides it's SbbLocalObject to the Enabler's Sbb, through a specific method exposed by the latter interface. The Enabler stores the Parent's SbbLocalObject and uses it when a callback to the Parent's Sbb is needed.

The SbbLocalObject which must be used or extended by the Parent's Sbb is named org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParentSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlParent interfaces, the latter declares the callbacks which must be implemented in the Parent's Sbb Abstract Class:



package org.mobicents.slee.sipevent.server.subscription;
import org.mobicents.slee.sipevent.server.subscription.data.Subscription;
public interface SubscriptionClientControlParent {
    public void subscribeOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires,
            int responseCode);
    public void resubscribeOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires);
    public void unsubscribeOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId);
    public void subscribeError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void resubscribeError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void unsubscribeError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void notifyEvent(String subscriber, String notifier,
            String eventPackage, String subscriptionId,
            Subscription.Event terminationReason, Subscription.Status status,
            String content, String contentType, String contentSubtype);
    
}
        
        

The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.

A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:



        <sbb-ref>
            <sbb-name>SubscriptionControlSbb</sbb-name>
            <sbb-vendor>org.mobicents</sbb-vendor>
            <sbb-version>1.0</sbb-version>
            <sbb-alias>sipEventSubscriptionClientChildSbb</sbb-alias>
        </sbb-ref>
        
        

The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:



        <get-child-relation-method>                 
            <sbb-alias-ref>sipEventSubscriptionClientChildSbb</sbb-alias-ref>
            <get-child-relation-method-name>getSIPEventSubscriptionClientChildRelation</get-child-relation-method-name>
            <default-priority>0</default-priority>
        </get-child-relation-method>
        
        

Finally, after the sbb-abstract-class element the Parent's SbbLocalObject interface name is defined:



        <sbb-local-interface>
            <sbb-local-interface-name>...</sbb-local-interface-name>
        </sbb-local-interface>
        
        

In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.

The Mobicents SIP Event Subscription Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sipevent.server.subscription.SubscriptionClientControlSbbLocalObject interfaces, the latter declares the methods which can be used to interact with the SIP Event Subscription Server:



package org.mobicents.slee.sipevent.server.subscription;
public interface SubscriptionClientControl {
    public void setParentSbb(
            SubscriptionClientControlParentSbbLocalObject sbbLocalObject);
    public void subscribe(String subscriber, String subscriberdisplayName,
            String notifier, String eventPackage, String subscriptionId,
            int expires, String content, String contentType,
            String contentSubtype);
    public void resubscribe(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires);
    public void unsubscribe(String subscriber, String notifier,
            String eventPackage, String subscriptionId);
}
        
        

The Mobicents SIP Presence exposes a JAIN SLEE enabler for applications which want to interact as clients of the Presence (PS) or Resource List Server (RLS). The enabler does not uses SIP network protocols, thus providing better performance and less overhead to network communications.

The Enabler consists in an SBB which can be used in child relations, with a simple asynchronous interface.

This chapter explains how to setup a JAIN SLEE Service Sbb to use the Enabler.

In short terms, a Service's Sbb will define the Enabler's Sbb as a child, and to achieve that it will need to setup the XML Descriptor, Abstract Class and SbbLocalObject interface.

The Mobicents Presence Client Enabler Sbb provides asynchronous callbacks to the Parent's Sbb, and that can only be achieved if the Parent's SbbLocalObject extends a specific Java interface, deployed also by the Enabler, and provides it's SbbLocalObject to the Enabler's Sbb, through a specific method exposed by the latter interface. The Enabler stores the Parent's SbbLocalObject and uses it when a callback to the Parent's Sbb is needed.

The SbbLocalObject which must be used or extended by the Parent's Sbb is named org.mobicents.slee.sippresence.client.PresenceClientControlParentSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sippresence.client.PresenceClientControlParent interfaces, the latter declares the callbacks which must be implemented in the Parent's Sbb Abstract Class:



package org.mobicents.slee.sippresence.client;
import org.mobicents.slee.sipevent.server.subscription.data.Subscription;
public interface PresenceClientControlParent {
    public void newPublicationOk(Object requestId, String eTag, int expires);
    public void refreshPublicationOk(Object requestId, String eTag, int expires);
    public void modifyPublicationOk(Object requestId, String eTag, int expires);
    public void removePublicationOk(Object requestId);
    public void newPublicationError(Object requestId, int error);
    public void refreshPublicationError(Object requestId, int error);
    public void modifyPublicationError(Object requestId, int error);
    public void removePublicationError(Object requestId, int error);
    public void newSubscriptionOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires,
            int responseCode);
    public void refreshSubscriptionOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires);
    public void removeSubscriptionOk(String subscriber, String notifier,
            String eventPackage, String subscriptionId);
    public void newSubscriptionError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void refreshSubscriptionError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void removeSubscriptionError(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int error);
    public void notifyEvent(String subscriber, String notifier,
            String eventPackage, String subscriptionId,
            Subscription.Event terminationReason, Subscription.Status status,
            String content, String contentType, String contentSubtype);
}
        
        
The newPublicationOk(Object, String, int) method:

Callback from the Enabler indicating that the new publication request succeed.

The refreshPublicationOk(Object, String, int) method:

Callback from the Enabler indicating that the refresh publication request succeed.

The modifyPublicationOk(Object, String, int) method:

Callback from the Enabler indicating that the modify publication request succeed.

The removePublicationOk(Object) method:

Callback from the Enabler indicating that the remove publication request succeed.

The newPublicationError(Object, int) method:

Callback from the Enabler indicating that the new publication request failed.

The refreshPublicationError(Object, int) method:

Callback from the Enabler indicating that the refresh publication request failed.

The modifyPublicationError(Object, int) method:

Callback from the Enabler indicating that the modify publication request failed.

The removePublicationError(Object, int) method:

Callback from the Enabler indicating that the remove publication request failed.

The newSubscriptionOk(String, String, String, String, int, int) method:

Callback from the Enabler indicating that the new subscription request succeed.

The refreshSubscriptionOk(String, String, String, String, int) method:

Callback from the Enabler indicating that the refresh subscription request succeed.

The removeSubscriptionOk(String, String, String, String) method:

Callback from the Enabler indicating that the remove subscription request succeed.

The newSubscriptionError(String, String, String, String, int) method:

Callback from the Enabler indicating that the new subscription request failed.

The refreshSubscriptionError(String, String, String, String, int) method:

Callback from the Enabler indicating that the refresh subscription request failed.

The removeSubscriptionError(String, String, String, String, int) method:

Callback from the Enabler indicating that the remove subscription request failed.

The notifyEvent(String, String, String, String, Subscription.Event, Subscription.Status, String, String, String) method:

Callback from the Enabler notifying an event related with notifier state change.

The Parent's Sbb must define a reference to the Enabler's Child Sbb, declare which is the method name to get the related ChildRelation object, and also ensure the SbbLocalObject interface is defined correctly.

A reference to the Enabler's Child Sbb is defined right after the Parent's Sbb Vendor ID element, using the following XML element:



        <sbb-ref>
            <sbb-name>InternalPresenceClientControlSbb</sbb-name>
            <sbb-vendor>org.mobicents</sbb-vendor>
            <sbb-version>1.0</sbb-version>
            <sbb-alias>presenceClientChildSbb</sbb-alias>
        </sbb-ref>
        
        

The method name to get the Enabler's ChildRelation object must be defined after the CMP Fields (if any), this XML element links the sbb-alias previously defined with the abstract method declared in the Parent's Sbb Abstract Class:



        <get-child-relation-method>                 
            <sbb-alias-ref>presenceClientChildSbb</sbb-alias-ref>
            <get-child-relation-method-name>getPresenceClientChildRelation</get-child-relation-method-name>
            <default-priority>0</default-priority>
        </get-child-relation-method>
        
        

Finally, after the sbb-abstract-class element the Parent's SbbLocalObject interface name is defined:



        <sbb-local-interface>
            <sbb-local-interface-name>...</sbb-local-interface-name>
        </sbb-local-interface>
        
        

In the last section we integrated the Enabler in the JAIN SLEE Service's Sbb, the Parent Sbb, in this section it is explained how to use the Enabler's Sbb, the Child Sbb.

The Mobicents Presence Client Enabler Sbb, the Child Sbb, implements the org.mobicents.slee.sippresence.client.PresenceClientControlSbbLocalObject, which extends the javax.slee.SbbLocalObject and org.mobicents.slee.sippresence.client.PresenceClientControl interfaces, the latter declares the methods which can be used to interact with the PS and/or RLS:



package org.mobicents.slee.sippresence.client;
public interface PresenceClientControl {
    public void setParentSbb(PresenceClientControlParentSbbLocalObject parentSbb);
    public void newPublication(Object requestId, String entity,
            String document, String contentType, String contentSubType,
            int expires);
    public void refreshPublication(Object requestId, String entity,
            String eTag, int expires);
    public void modifyPublication(Object requestId, String entity, String eTag,
            String document, String contentType, String contentSubType,
            int expires);
    public void removePublication(Object requestId, String entity, String eTag);
    public void newSubscription(String subscriber,
            String subscriberdisplayName, String notifier, String eventPackage,
            String subscriptionId, int expires);
    public void refreshSubscription(String subscriber, String notifier,
            String eventPackage, String subscriptionId, int expires);
    public void removeSubscription(String subscriber, String notifier,
            String eventPackage, String subscriptionId);
}
        
        
The setParentSbb(PresenceClientControlParentSbbLocalObject) method:

Passes the Parent's SbbLocalObject, which will be used by the Child Sbb to provide async results. If not invoked after the child creation the Enabler won't be able to callback the Parent Sbb.

The newPublication(Object, String, String, String, String, int) method:

Requests a new publication, for the specified Entity. The object argument is an ID that identifies the publication, and which will be provided in the response callback.

The refreshPublication(Object, String, String, int) method:

Requests a publication refresh, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.

The modifyPublication(Object, String, String, String, String, String, int) method:

Requests a publication modification, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.

The removePublicationOk(Object, String, String) method:

Requests a publication removal, for the specified Entity and ETag. The object argument is an ID that identifies the publication, and which will be provided in the response callback.

The newSubscription(String, String, String, String, String, int) method:

Requests a new subscription.

The refreshSubscription(String, String, String, String, int) method:

Requests a subscription refresh.

The removeSubscription(String, String, String, String) method:

Requests a subscription removal.

The Child Relation in the Parent Sbb Abstract Class is used to create and retrieve the Child Sbb, it is important to not forget to pass the Parent's SbbLocalObject to the Child after creation:



    public PresenceClientControlSbbLocalObject getPresenceClientChildSbb() {
        final ChildRelation childRelation = getPresenceClientChildRelation();
        if (childRelation.isEmpty()) {
            try {
                // creates new instance
                PresenceClientControlSbbLocalObject sbb = (PresenceClientControlSbbLocalObject) childRelation.create();
                // passes the parent sbb local object to the child
                sbb.setParentSbb((PresenceClientControlSbbLocalObject) sbbContext.getSbbLocalObject());
                return sbb;
            } catch (Exception e) {
                tracer.severe("Failed to create child sbb", e);
                return null;
            }
        }
        else {
            // reuse the existent one
            return (PresenceClientControlSbbLocalObject) childRelation.iterator().next();
        }
    }
        
        

The SbbLocalObject of the Child could also be stored in a CMP Field for the simplest retrieval, but unless you are going to reuse each instance several times it's better to have less state, specially in clustered environments.

TODO